NGINX Conf 2018 


N | 
ZZ 


LA EA 


Why make your own 
NGINX modules? 

Theory and Practice 
Vasiliy Soshnikov, Mail.Ru Grog 


vasiliy.soshnikov@gmail.com 2 


Agenda 


1 Why make your own modules? 
Foreword 

HTTP modules anatomy 
Handlers, Filters and Proxies 


References and Q&A 


OJ P$ Cc IN 


Why make your own modules? 


* To add new features 
* To solve problems and business issues 


And many other modules 


Add header 


Internet analytics & statistics 


* To set special cookies 
* [o collect special logs. 


Advertisement - Ads 


* To return banners in real-time (typical internet ads) 
* To collect ads statistics. 


Special Proxies 


e To convert HTTP to X (in present case in MsgPack) protocol 
* To load balancing 
e To have failover 


e More features: 
http://nginx.org/en/docs/http/ngx http upstream module.html. 
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Foreword. NGINX Architecture 


Foreword. NGINX Memory model 


* Pool allocation - means you don't need to use "free()" 
functions 


e You have to choose a right pool! 


e Try to use NGINX memory functions which allows to work 
with NGINX pools 


* Avoid external functions like “malloc()”. 


Sources: nginx/src/core/ngx_palloc.h Q 
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A reference to pool 5 


ngx. conf s 
ngx array t 


ngx cycle t 

ngx pool t 

ngx pool t 

ngx conf file t 
ngx log t 


ngx uint t 
ngx uint t 


ngx.conf. handler. pt 


"name ; 
*args; 


*cycle; 
*pool ; 
*temp_pool ; 
*conf_file; 
*log; 


*ctx; 
module. type; 
cmd type; 


handler; 
“handler. conf ; 


Foreword. NGINX is a framework 


e Data structures: B-tree, Hash, Array, List, Radix tree etc. 
e OS API: File I/O, Shared Memory etc. 


* Event-driven state machine: polling and timers. 


Sources: nginx/src/core/*, nginx/src/http/*, nginx/src/event/*, nginx/src/os/* Q 


11 


Chain of Responsibility 


Module 1 Em N 


Chain of Responsibility 


Analogy pattern is (bash-script): 


grep -RI pool nginx | awk -F":" ‘{print $1}' | sort -u | wc -l 


Phases 


Module 1 Module N 


Module 1 Module N 


Module types 


e Phase handlers 
e Header and Body filters 
e Proxies 


* Load balancers 


Practice 


Foreword 


1. A module begins with 
configuration. 


2. Highly recommended naming 
policy is: 


ngx_http_ _£main, srv, loc; 


where NAME is a module name. 


} ngx http MODULE. NAME main conf t; 


{ 


} ngx http MODULE NAME srv. conf t; 


d 


} ngx http MODULE. NAME loc. conf t; 


location /my location/ { 
add header "My-Header" "my value": 


} 


*(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); 
conf; 
offset; 


“AK fL ^) 
( f) © H 
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ypedef struc 
ngx int t integer value, 
} ngx http MODULE. NAME loc conf t; 


static ngx command t ngx http MODULE NAME commands[] = { 


{ ngx string( 
NGX HTTP. MAIN CONF |NGX HTTP. SRV. _CONF | NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx conf set num slot, 
NGX HTTP. LOC. CONF. OFFSET, 
offsetof(ngx http MODULE NAME loc conf t, integer value), 


}, 


ngx. null. command 
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typedef struct f 


ngx int t 
ngx int t 


void 
char 


void 
char 


void 
char 


(*preconfiguration)(ngx conf t *cf); 
(*postconfiguration)(ngx conf t *cf); 


“(create main conf )(ngx conf t *cf); 
#Cinit main conf)(ngx conf t "cf, void *conf); 


*(*create. srv. conf)(ngx conf t *cf); 
*C*merge srv conf)(ngx conf t "cf, void "prev, void *conf); 


*(*create. loc conf)(ngx conf t *cf); 
*C*merge loc conf)(ngx conf t "cf, void “prev, void *conf); 


3 ngx http module t; 


LL / Loe ce f 

Ffn/ nav Attn rnnfın I^ 

Ctp/ngx_Nttp_conj7g.n 
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Add a new module 


Example: 


&ngx. http MODULE NAME module ctx, /* module context */ 
ngx http MODULE NAME commands, 7/* module directives */ 
NGX HTTP. MODULE, /* module type */ 

/* init master */ 

/* init module */ 


/* init process */ 
/* init thread */ 
/* exit thread */ 
/* exit process */ 
/* exit master */ 


NGX. MODULE. VI PADDING 
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Phases 


Module 1 Module N 


Module 1 Module N 


Phases 


NGX HTTP. POST. READ. PHASE = 0, 


NGX HTTP. SERVER REWRITE. PHASE, 
NGX HTTP. FIND CONFIG, PHASE, 
NGX HTTP. REWRITE. PHASE, 

NGX HTTP. POST. REWRITE. PHASE, 


NGX HTTP. PREACCESS PHASE, 


NGX HTTP. ACCESS. PHASE, 
NGX HTTP. POST. ACCESS. PHASE, 


NGX HTTP. PRECONTENT. PHASE, 
NGX HTTP. CONTENT. PHASE, 


NGX. HTTP. LOG. PHASE 
+ ngx http phases; 


Sources: nginx/src/http/ngx http core module.h 
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static ngx http module t  ngx http MODULE. NAME. module. ctx = 4 
ngx http. MODULE. NAME init, 


}; 
static ngx_int_t 
ngx_http_MODULE_NAME_init(ngx_conf_t “cf) 
d 
ngx http handler pt *h; 
ngx http. core main conf t *cmcf; 


cmcf = ngx http. conf. get. module main conf(cf, ngx http. core module); 
h = ngx array. push(&amcf -»phases [NGX. HTTP. CONTENT. PHASE] .handlers); 


if (h = NULL) f 
return NGX ERROR; 
} 


*h = ngx http MODULE. NAME handler; 


return NGX OK; 
} 


static ngx_int_t 
ngx_http_MODULE_NAME_handler(ngx_http_request_t *r) 
{ 


return NGX_DECLINED; 
} 
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Header ana Body 
filters 


Chain of Responsibility 


Analogy pattern is (bash-script): 


grep -RI pool nginx | awk -F":" ‘{print $1}' | sort -u | wc -l 
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static ngx http module t ngx http MODULE. NAME module. ctx = { 
ngx http MODULE NAME filter init, 


y; 
static ngx_int_t 
ngx_http_MODULE_NAME_fheader, body) filter(ngx http request t *r) 


} 
static ngx_int_t 
ngx_http_MODULE_NAME_filter_init(ngx_conf_t *cf) 
i 
ngx http next header filter - ngx http top header filter; 
ngx http top header filter - ngx http MODULE NAME header. filter; 


ngx http next body filter - ngx http top body filter; 
ngx http. top body filter - ngx http MODULE. NAME. body. filter; 


return NGX OK; 
} 


Proxies 


Anatomy 


Native protocol — 
[ Application server 


Proxy tt balancing 


Registration 


[1] Add a new directive. 


[2] Add a new upstream. 


[3] Add a new handler to 
the added upstream. 
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static ngx command t ngx http tnt commands[] = 4 


i ngx string("tnt pass"), 
NGX HTTP LOC, CONF |NGX HTTP. LIF. CONF|NGX CONF TAKE1, 


ngx http tnt pass, 
NGX HTTP. LOC. CONF. OFFSET, 


ngx http tnt pass(ngx conf t *cf, ngx command t xcmd, xconf) 
ngx http tnt loc conf t xmlcf = conf; 
ngxestret *value; 
ngx url t u; 
ngx http core loc conf t xclcf; 
value = cf->args->elts; 
V Leer 


u.url = value[1]; 
u.no resolve - 1; 


mlcf-»upstream.upstream = ngx http upstream add(cf, ču, 0); pl 
[V 


clcf = ngx http conf get module loc conf(cf, ngx http core module); 


clcf-»handler = ngx http tnt handler; BI 


return NGX CONF OK, 


Content handling static ngx int t 


ngx http tnt filter init( xdata); 
static ngx int t 
ngx http tnt filter( xdata, 
{ 
[1] Invoked on request. E-slast m D-vlost € bytes; 
ngx int t rc - NGX OK; 


for Gp { 


[2] Create Upstream & rc = ngx http tnt filter reply(r, u, b): 
if (rc != NGX AGAIN) 
Downstream (or getting from break: 
KeepAlive module). } 
return rc; 
} 
[3, 4] Add handlers & filters (also H — | 
it converts the request to the A ee te Teen S nn 
ngx_ p_tnt_handler(ngx_ p_request_ NG 
backend request). { 


er 
[5] Read backend reply. "ax etg set content vpeto: | 


ngx http. upstream create(r); 


re = noX http tnt init handlers(e, u, tich); 


u-»input filter init = ngx http tnt filter init; 
u-»input filter - ngx http tnt filter; 
u->input filter ctx = rj 


rc - ngx http read client request body(r, ngx http upstream init); 


return NGX DONE; 
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References 


https://github.com/dedok/nginx-tutorials — tutorials 


https://github.com/tarantool/nginx_upstream_module — an example of Proxy (a real 
project) 


https://www. nginx.com/resources/wiki/modules/ — about NGINX modules 


http://nginx.org/en/docs/dev/development guide.html — a development guide 
nginx.org — NGINX web site. 


NGINX — 


- Thank you! 


Contact information: 


vasiliy.soshnikov @gmail.com 
GitHub: @dedok 


